Running playbooks

Select the File operations playbook to remotely:

• Download a file to a device from a server or one of the following file hosting services:
  • Box
  • Dropbox
  • Google Drive
  • OneDrive
• Delete a file from a specified location on a device.

Your playbook can include up to 20 file actions.

Requirements

• If the device's drive is encrypted by BitLocker Drive Encryption, you must enter the device's BitLocker recovery key in the playbook configuration.
• If you are adding a file:
  • The device must be using a physical ethernet network connection.

  • The file must be stored in a location that is not password-protected.

    To ensure the file is secure, it's best practice to create an AWS pre-signed URL.

Select the Restore from image playbook to use an image A snaphot of a hard drive that includes the operating system, settings, and installed software required by your organization. It serves as a template to ensure consistent and efficient device provisioning. It is also known as a system image or a base image. to remotely reimage an existing device, or set up a new device.

Requirements

• The image has been created and stored in an accessible location. Password-protected locations are supported.

  If the location is not password protected, it's best practice to create an AWS pre-signed URL.

• The file format of the image is one of the following:
  Windows ISO file

  Ensure that the following files are uploaded to the storage location:

  • Windows installation ISO file (.iso)

  • Answer file (unattend.xml)

    For more information about creating an answer file, see Microsoft documentation.

  • Manifest file in JSON (.json) file format

    This file contains the URL to each of the above files. For example:

    Copy

    {
        "answer_file": "https://abc.server.com/unattend_win11.xml",
        "image_file": "https://abc.server.com/win11_business_24h2.iso"
    }

  Captured Windows image

  Ensure that the following files are uploaded to the storage location:

  • Windows image (.wmi)

    To capture an image, ensure that you follow the instructions provided in Microsoft documentation.

  • Manifest file in JSON (.json) file format

    This file contains a parameter that resets (removes and recreates) a device's partitions, and contains the URL to the Windows image file. For example:

    Copy

    {
      "reset_par":true,
      "image_file": "https://abc.server.com/image_win11.wim"
      }

• The device is using a physical ethernet network connection.

Select the Run script playbook to remotely run a script on a Windows device.

Note that the script content is pasted into a text field in the Run playbook dialog. You can't upload a file.

Requirements

• The script must be a batch script (.bat) or a PowerShell (.ps1) script.

  • For PowerShell scripts, ensure that "#PS" is added at the beginning of the script.

  • Batch scripts that use the set command to define variables, such as %filepath%, are not supported.

• The script cannot exceed 3 KB in size.

• If the device's drive is encrypted by BitLocker Drive Encryption, you must enter the device's BitLocker recovery key in the playbook configuration.

Select the Set/remove registry keys playbook to remotely:

• Add a registry key
• Update a key value
• Remove a key value

Your playbook can include up to 20 registry key actions.

When editing the Windows registry, always proceed with caution. A misconfiguration can lead to significant issues, such as system instability, application errors, or an inability to restart Windows. Ensure that you understand the full impact of your registry edits before running this playbook. For more information about the Windows registry, see Windows documentation.

Requirements

• If the device's drive is encrypted by BitLocker Drive Encryption, you must enter the device's BitLocker recovery key in the playbook configuration.

• The HKEY_LOCAL_MACHINE registry hive is supported.

  Other registry hives, such as HKEY_CURRENT_USER, are not supported.

• Removal of a registry key is not supported. You can only remove registry key values.

Format guidelines

When entering registry paths, ensure that you use:

• HKEY_LOCAL_MACHINE for the registry hive. HKLM is not supported.

• Backslashes (\)

For example, HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

When you submit a Run playbook request, you need to configure the User initiated playbook option, which controls how the playbook will be launched. There are two options:

If a Run playbook request is already in progress on a device, you can submit a user-initiated playbook, but not a system-initiated playbook.

To run a playbook, your user role needs to be granted the Perform permission for Run playbook.

To view the following interface items on a device's Device Details page, your user role needs to be granted the View or Perform permission for Run playbook:

• Playbook requested banner
• Playbooks field

All default Administrator roles are granted these permissions.

To run a playbook, the following prerequisites must be met:

• The device meets the system requirements for this action.
• The device has not been reported stolen.
• The Playbooks policy is activated in the device's policy group.
• The device's Playbooks field shows a value of Enabled, meaning it is provisioned. Learn more
• At least 24 hours have elapsed since the policy was activated.

Before running a playbook, you need to verify that each device is provisioned for the Playbooks feature.

To view a device's provisioning status:

1. Log in to the Secure Endpoint Console as a user with the View or Perform permission for Run playbook.
2. Navigate to the Windows device's Device Details page.
3. Click the Details tab.
4. On the Summary page, scroll to the bottom of the first table of information and view the Playbooks field. Possible values are:

   • Enabled: the Playbooks policy is activated on the device, and the device is provisioned to run playbooks.

     An obscured passcode () is also displayed. Learn more

     After the policy is activated, and the Playbooks field is set to Enabled, it may take up to 24 hours for the device to be fully provisioned. Attempts to run a playbook during this time may fail.

   • Not enabled: one of the following applies:
     • The Playbooks policy is activated in the device's policy group, but the device is not yet fully provisioned to run playbooks. A restart may be required.
     • The Playbooks policy is not activated in the device's policy group
     • The device does not meet the system requirements for the Playbooks feature

     The device is not provisioned to run playbooks.

If a device fails to be provisioned, see the following articles in the Knowledge Base to help troubleshoot the issue:

• Manual Enable ABT in Boot Sequence
• Manual install of Microsoft 3rd Party UEFI CA

While configuring playbooks, you may need to enter device specific information, such as a file path on a device, or a device's BitLocker recovery key. You can use variables to specify this type of information. When the playbook runs on a device, the variable is replaced by the specific value for that device.

If you are submitting a request for multiple devices, and the playbook configurations require device specific information, you will most likely need to use a variable.

Playbooks support three types of variables:

• Hardware (select fields only)

• Custom Fields

• Custom Data Points

You can view the complete list of supported variables by clicking View list of variables on the Run playbook dialog. To add a variable to a field, click its Insert variable field and then search for and select a variable from the list.

Variables are not supported within a batch script in the Run script playbook.

To run a playbook:

1. Log in to the Secure Endpoint Console as a user with the Perform permission for Run playbook.

2. Do one of the following:

   To run a playbook on a single device

   On the Windows device's Device Details page, click > Run playbook.

   If a icon shows when you hover over Run playbook, the device is not eligible for the action.

   To run a playbook on multiple devices

   1. From the navigation bar, open a page that supports the Run playbook action. For example, open the All Devices page in the Devices area or open the Makes and Models report.
   2. In the work area, use the search field or filters to find the applicable Windows devices.

   3. In the results grid, select each device you want to include in the request. To select all devices, select the Select All checkbox in the result grid header. To select consecutive devices, select the first device and then hold down the Shift key and select the last device. You can select up to 1000 devices. To remove all selections, click Clear all.

   4. Click > Run playbook.
3. Under Playbook, click the Select playbook field and select one of the following playbooks:
   • All playbook parameter fields include an Insert variable field, which is optional . Learn more about using variables
   • The system does not validate the values that you enter in each playbook's parameter fields. To help ensure that a playbook runs successfully, verify the parameters before adding them, and then enter them carefully. If a playbook fails to run successfully, a Playbook failed event is logged to Event History.
   File operations (add or delete)

   1. Review the playbook's requirements.

   2. Under Parameters, enter the device's BitLocker recovery key.

      If the device is not encrypted by BitLocker Drive Encryption, skip this step.

      If the device is encrypted by another encryption product, the playbook will fail to run.

   1. Click Add action and do one of the following:
      Add a file

      1. Click Add file.
      2. In the Host file URL field, enter the URL(HTTP or HTTPS protocol only) for the location where the file is stored.

      3. In the File path field, enter the full path and file name of the location on the device to save the file. You can use the original file name, or a file name of your choosing, but do not change the file extension.

         For example, enter C:\Documents\Temp\Filename.txt

         Note the following:

         • Environment variables are not supported.
         • If a file with the same file name already exists in the location, the file is replaced by the downloaded file.
         • If a folder in the specified path doesn't exist, the folder is created.
         • The added file's Date modified timestamp is based on the device's real time clock (RTC). If the device's display time has been adjusted in Windows date & time settings, the timestamp may not be in sync with the display time.
      Delete a file

      1. Click Delete file.

      2. In the Path and file name to delete field, enter the full path to the file that you want to delete, including the file name. For example, enter C:\Documents\Textfile.txt. Environment variables are not supported.

   2. To add another action, repeat step c. The playbook can include up to 20 actions. To remove an action, click its icon.

      If one action in the playbook fails, a Playbook failed event is logged to Event History, even if all other actions in the playbook are completed.

   Set/remove registry keys

   1. Review the playbook's requirements.
   2. [Optional] Open the Registry Editor on your local machine and find the key that you want to update or remove. For example:
      1. In the Windows Search field, type regedit.
      2. Click Registry Editor and click Yes in the User Account Control dialog.

      3. Navigate to the registry key and make note of the Name, Type, and Data of the registry key value. Also note the registry key path.

         

      4. Return to the Secure Endpoint Console.

   3. Under Parameters, enter the device's BitLocker recovery key.

      If the device is not encrypted by BitLocker Drive Encryption, skip this step.

      If the device is encrypted by another encryption product, the playbook will fail to run.

   4. Review the playbook's format guidelines.
   5. Click Add action and do one of the following:
      Add a registry key

      1. Click Set registry key.
      2. In the Registry path field, enter the path to the location where you want to add the new registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

      3. In the Registry name field, enter the name of the registry key value you want to add. In Registry Editor, this will show under Name.
      4. Under Registry type field, select the registry key's type. In Registry Editor, this will show under Type.
      5. In the Registry value field, enter the data associated with the value. In Registry Editor, this will show under Data.
      Update a registry key value

      1. Click Set registry key.
      2. In the Registry path field, enter the path to the registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

      3. In the Registry name field, enter the name of the registry key value. In Registry Editor, this shows under Name.
      4. Under Registry type field, select the registry key's assigned type. In Registry Editor, this shows under Type.
      5. In the Registry value field, enter the new data string. In Registry Editor, this value will replace the value under Data.
      Remove a registry key value

      1. Click Remove registry key.

      2. In the Registry name field, enter the name of the registry key value that you want to remove. In Registry Editor, this is the value under Name.

         You can't remove the (Default) value.

      3. In the Registry path field, enter the path to the registry key.

         For example, enter HKEY_LOCAL_MACHINE\SOFTWARE\TestApp

   6. To add another action, repeat step d. The playbook can include up to 20 actions. To remove an action, click its (Remove) icon.
   Restore from image

   1. Review the playbook's requirements.
   2. Under Parameters, in the Manifest file URL field, enter the URL (HTTP or HTTPS protocol only) for the location where the manifest file is stored.
   3. [Optional] If credentials are required to access the server, enter the applicable Username and Credentials (password, key, etc).
   Run script

   1. Review the playbook's requirements.
   2. Under Parameters:

      1. Enter the device's BitLocker recovery key.

         If the device is not encrypted by BitLocker Drive Encryption, skip this step.

         If the device is encrypted by another encryption product, the playbook will fail to run.

      2. Open the script on your local machine and copy its contents.

      3. Click the Batch script text field and paste the script content.

         If the script content exceeds 3 KB in size, an error message shows.

4. Under User initiated playbook, do one of the following:
   • If the device's operating system is fully operational, leave the toggle set to Off (gray).

     When the option is disabled (Off), the Run playbook request is deployed to the device on its next connection to the Absolute Monitoring Center, and the playbook runs automatically.

     To complete the Run playbook request, the Secure Endpoint Agent forces the device to restart. If a device user is logged in at this time, they are automatically logged out and data may be lost. Therefore, before submitting a Run playbook request, contact the device user and instruct them to save their work.

     Alternatively, if you want to run a script on a device, consider running a Reach script instead of the Run script playbook. The Reach script may not require a restart.

   • If the device's operating system won't boot up, click the toggle to set it to On (green). Note that if a playbook is already in progress on the device, the toggle defaults to On and it can't be changed.

     When the User initiated playbook option is enabled (On), the device must be using a physical ethernet network connection.

     Learn more about user-initiated playbooks
     

5. Click Run on x devices.

   The request is created. A Playbook requested banner is added to each device's Device Details page, and a Playbook requested event is logged to Event History.

6. If you submitted a user-initiated playbook, go to the next section.

You can track the progress of a system-initiated Run playbook request on the device's Actions page, or in Action History. When the request is processed, one of the following events is logged to Event History:

• Playbook completed
• Playbook failed

If you enabled the User initiated playbook option in a Run playbook request, the following tasks need to be completed to initiate the playbook:

1. Get the device's Playbooks passcode
2. Initiate the playbook locally on the device

The first task is performed in the Secure Endpoint Console by an Administrator, while the second task is performed locally on the device by the device user. Note that it is best practice to maintain phone contact with the device user to guide them through the steps in the second task.

Prerequisite

You submitted a Run playbook request with the User initiated playbook option set to On. Learn more

Getting the device's passcode

To allow the user-initiated playbook to run, the device user needs to enter the device's Playbooks passcode during the boot process.

To get the device's passcode:

1. Log in to the Secure Endpoint Console as a user with the View or Perform permission for Run playbook.
2. Navigate to the device's Device Details page.
3. Click the Details tab.
4. On the Summary page, scroll to the bottom of the first table of information and view the Playbooks field.
5. Next to Enabled, click to view the passcode.
6. Leave the page open and go to the next section.

Initiating the playbook

The device user must perform the steps in this task. If they are unable to receive written instructions (due to the fatal system error), contact them by phone or text message.

To run a user-initiated playbook:

1. Provide the Playbooks passcode from step 5 to the user. Optionally ask them to record it somewhere temporarily.
2. Instruct the user to:
   1. Restart the device.
   2. When the manufacturer logo appears, press F6 (or Fn+F6, as applicable) repeatedly until an Absolute branded window opens.
   3. In the passcode field, enter the passcode from step 1 and then press Enter to initiate the playbook.

      The passcode window is only available for 2 minutes. If the user fails to enter a valid passcode before the window closes, instruct them to press F6 (or Fn+F6, as applicable) again. Note that after three failed passcode attempts, the device automatically boots into Windows.

   4. Wait while the playbook runs. Note that the device will automatically restart to complete the recovery operation. If the Restore from image playbook was requested, the device will restart multiple times. Do not perform a manual restart while the playbook is running.

      If the operating system loads after a restart, the playbook ran successfully.

   For user-initiated playbooks:

   • No events are logged to Event History after the playbook has finished running.
   • You can't track the progress of the request in Action History.